missionmaker.txt
================
Version 1.1
Updated 17 Jul 2010

CHERNARUS ELECTRICAL GRID SCRIPT PACK AND ADDON
by Loyalguard


*** PLEASE READ README.TXT BEFORE THIS FILE ***

===========================
Guidance for Mission Makers
===========================

I. Mission Maker Overview
II. Script Version Implementation
III. Script Version Implementation
IV. Customization Options
V. Special Considerations


I. MISSION MAKER OVERVIEW
=========================

The Chernarus Electrical Grid (CEG) simulation was designed to be easily implented, customized, and used.  Below are instructions on how to implement the addon and script versions of CEG, how to customize certain options, and special considerations when using CEG. 


II. Addon Version Implementation
================================

The following step is optional, but recommended to ensure that players have the CEG addon installed and loaded.  If they do not they will receive a warning message when trying to load the mission.

1. In the mission editor, insert a CEG Logic anywhere on the map.
	a. To find CEG Logics, For the side choose "Game Logic".
	b. For the class choose "CEG Logics".
	c. By default the only available unit should show as "CEG Logic".

Again, if the the server/player has the CEG addon installed, it will initialize regardless of whether or not this logic is present. But, presence of this custom logic will require CEG for your mission.  No other steps are necessary to implement the addon version.


III. Script Version Implementation
==================================

If you do not want addon dependencies for your mission, follow these instructions.  If a player has the addon version installed, the mission script version will override it and be used to ensure full compatibility.

A. CEG Folder
-------------
Place the CEG folder inside your mission folder.


B. Description.ext
------------------
1. Modify the Description.ext file.  This is necessary to ensure custom sounds and dialogs from the CEG simulation can be used in the mission:

2. Copy the following #include line:

       #include "CEG\Sounds\CEG_Sounds.hpp"

3a. Paste the above line into class CfgSounds of the Description.ext.  Do NOT insert a semi-colon after the #include line.  When pasted, class CfgSounds should look like this:

class CfgSounds
{
   sounds[] = {};
   #include "CEG\Sounds\CEG_Sounds.hpp"

   //Insert other custom sounds or #include lines for your mission here.
};

3b. If you have other custom sounds or sound #include lines, insert them as indicated in the example above.

4. Copy the following #include line:

       #include "CEG\Dialogs\CEG_Dialogs.hpp"

5. Paste the line into the Description.ext.  Exact placement position is not required but it is recommended to paste near where you have defined any custom resources or other dialog classes.  Do NOT insert a semi-colon after the #include line.

*** AN EXAMPLE OF THE ABOVE DESCRIPTION.EXT MODIFICATIONS CAN BE FOUND IN THE CEG SCRPT DEMO MISSION FOLDER.


C. Mission Editor
-----------------
1.  Place a unit in the editor.  It is recommended to use a game logic but any unit placed in the editor will work.  The unit does not need a name but it can be named if desired/required.

2.  Copy the following line of code:
   nul = ["SCRIPT"] execVM "CEG\Scripts\CEG_init.sqf";

3.  Paste the code from step 2 into the unit init line from step 1.

***AN EXAMPLE OF THE ABOVE UNIT INIT LINE CODE CAN BE FOUND IN THE CEG SCRIPT DEMO MISSION FOLDER.


Iv. Customization Options
==========================

There are two primary features that a mission maker can customize.  These are optional and do not require mission maker action unless desired.  CEG is also mission task friendly by utilizing existing global/public variables.

A.  Manual Power Control
------------------------

1. Enable/Disable Manual Action Menu Control
--------------------------------------------

By default, when facing the center of a substation transformer object, players have the ability to trip a circuit breaker to turn power off or close a circuit breaker to turn power on.  If you do NOT want players to have this ability, insert the following line of code somwhere in your mission.  It is recommended that you place it in the init.sqf:

CEG_manual = false;

If you use this code at any other point in your init.sqf or elsewhere in the mission, just ensure that it is run on all clients.

2. Arc Flash Explosions
-----------------------

Mission makers can also add the possibility of an arc flash explosion whenever circuit breakers are manually switched. An arc flash is a potentially lethal explosion caused by a fault in a high-voltage electrical system.  By default, the chance of arc flash is zero.  In order to add a chance of arc flash, the mission maker need only assign a value (integer) to the variable CEG_explode.  The value reflects the "odds" that an arc flash might occur.  Assigning a value of 1 ensures that an arc flash will occur 1 in every 1 times (i.e. every time), 4 means 1 in 4 times, 100 means 1 in a 100 times, etc.   Do NOT assign a value of zero as this has the same effect a 1.  If you do not want a chance of arc flash then leave CEG_explode nil.  Below is example code to  make an arc flash occur 1 in every 100 times a breaker is manually switched:

CEG_explode = 100;

It is recommended to run this code on all clients (such as the init.sqf or other code that runs on all clients) in order to ensure that the odds are the same on all machines.


B.  "Remote" Control of Grid "Software"
---------------------------------------

Mission makers can allow players to access the grid control system (a custom dialog) to be able to remotely turn power on and off as well as see live video feeds from the seven substations. The easiest way to allow access is to add an action menu item to the init line of an object in the editor (such as the notebook computer).  Below are examples of this this method that do not require a password and that do require a password.

*SPECIAL NOTE: Mission makers should be aware that controlling power manually by switching breakers and controlling power remotely via the grid control system dialog use the same "process" to turn power on and off (by controlling circuit breakers).  So if one player turns power off by manually switching a breaker at a substation, another player logged on to the dialog can turn power back on and vise versa.

1. No Password Required
-----------------------

By default no password is required in CEG.  The easiest way to allow access would be to add the following code to an editor object (as mentioned above):

this addaction ["Log On", "CEG\Scripts\CEG_logon.sqf"];

This will directly open the custom grid control dialog.


2. Password Required
--------------------

In order to require a password to access the system, all the mission maker needs to do is to declare a string value for the variable CEG_password somewhere in the mission and add the same code as above to the editor object:

(in the init.sqf or elsewhere):

CEG_password = "abc123";


(in the editor):

this addaction ["Log On", "CEG\Scripts\CEG_logon.sqf"];

The password MUST be a string (even if only numbers).  It is recommended to run this code on all clients (such as the init.sqf or other code that runs on all clients) or some clients may be able to access the system without a password if CEG_password is left nil (since it is nil by default).


3. Mixed Access
---------------

If a mission maker wants to require a password in some circumstances but not in others, mixed access can be achieved.  To require a password follow the example in number 2 above (declare a value for CEG_password and add the init line code for CEG_logon.sqf).  To allow access without a password (even if one is declated via CEG_password) add the alternate editor line code below to a different object:

this addaction ["Log On", "CEG\Scripts\CEG_system.sqf"];

This code bypasses the password entry screen regardless of whether a password is declared in CEG_password and directly opens the control system dialog by executing CEG_system.sqf instead of CEG_logon.sqf.


Examples:
---------

Examples of the above can be found in the demo mission.  Inside the shack near the power plant in Elektrozavodsk there is a notebook computer that requires a password to access the system.  the password is: abc123
If this password is commented out or deleted in the demo mission init.sqf NO password will be required.

Inside the shack near the power plant in Chernogorsk there is a notebook computer that does NOT require a password to access the system by using the method described in number 3 above (executing CEG_system.sqf).


C. CCTV System
--------------

The CCTV system can be accessed from within the grid control dialog.  If PP effects are enabled, then there will be some "static" on screen when the cameras are displayed.  By default, there is no low light or night vision capablity for the CCTV system.  If the mission maker would like the CCTV cameras to be able to use night vision, insert the following line of code somwhere in your mission.  It is recommended that you place it in the init.sqf:

CEG_NVG = true;

If enabled, the default start time for camera night vision is 1900 and end time is 0600.  If the mission maker would like to customize these times, declare new integer values (24-hr clock) for CEG_dark (start time) and CEG_light (end time).  Examples:

CEG_dark = 21;
CEG_light = 5;


D. Mission Task Support
-------------------------------------
In addition to the realism and immersion gained from the functionality of the grid, mission makers can also use the public/global variables that make the grid function for mission-based tasks.  Below is example code that can be found in a script called berezinoPowerTask.sqf in the CEG Demo Mission Folder.

Example Code:


// berezinoPowerTask.sqf //

// Create Task.
berezinoPower = player createSimpleTask ["Cut Berezino Power"];

// Set Task Description.
berezinoPower setSimpleTaskDescription ["Cut off power in Berezino by destroying the substation transformer or tripping the circuit breaker.", "Cut Berezino Power", "Cut Berezino Power"];
//player setCurrentTask berezinoPower; // Uncomment to force this task.

// Task successful when Berezino power is off.
waitUntil {!(CEG_on_D_Bere)};
berezinoPower setTaskState "SUCCEEDED";

// End Script //
 

E. CEG City/Town/Area and Variable List
----------------------------------------
 
Below is a list of all of the cities and town in South Zagoria and the CEG variables that are associated with power in those areas.  Use this list to determine which variables you would like to use for task conditions as well as to monitor power in specific cities and towns.  In addition to this list, the CEG Demo Mission displays a series of color-coded zones on the map showing which areas are affected by which substation transformers.  If a city/town/area is inside one of the colored circles on the map, its power is controlled by the substation transformer marked with the same color square icon for ease of identification. 

Substation/Transformer: Elektrozavodsk / D_Elek
Variable: CEG_on_D_Elek

Cities/Towns/Areas:
Elektrozavodsk
Zelenaya Coast
Kamyshovo
Skalisty
Golova
Topolka
Pusta
Prigorodki

---

Substation/Transformer: South Zagoria Regional / D_SZag
Variable: CEG_on_D_SZag

Cities/Towns/Areas:
Nadezhdino
Mogilevka
Vyshnoye
Guglovo
Novy Sobor
Stary Sobor
Kabinino
Dosnovka
Myshkino
Pustoshka
Vybor
Lopatino
Northern Airfield
Grishino
Petrovka
Skalka

---

Substation/Transformer: Chernogorsk / D_Cher
Variable: CEG_on_D_Cher

Cities/Towns/Areas:
Chernogorsk
Mutnaya Coast
Balota
Balota Airstrip
Vysota
Komarovo

---

Substation/Transformer: Zelenogorsk / D_Zele
Variable: CEG_on_D_Zele

Cities/Towns/Areas:
Zelenogorsk
Drozhino
Pavlovo
Bor
Windy Mountain
Kozlovka
Green Mountain
Pogorevka
Rogovo
Pulkovo
Kamenka

---

Substation/Transformer: Berezino / D_Bere
Variable: CEG_on_D_Bere

Cities/Towns/Areas:
Berezino
Khelm
Orlovets
Dubrovka
Gorka
Gvozdno
Krasnostov
Krasnostov Airstrip
Olsha

---

Substation/Transformer: Solnichniy / D_Soln
Variable: CEG_on_D_Soln

Solnichniy
Three Valleys
Dolina
Tulga
Nizhnoye
Msta
Polana
Shakhova
Staroye

F. Pre-Planned Power Outages
----------------------------
 
1. Temporary / Correctable Outages

If a mission maker would like to start a mission with power off (or do so at any other time) and have players be able to restore it, the easiest way to accomplish this is to manipulate the power flowing "out" of a substation transformer.  Do not attempt to change a "on" variable as given above.  Any change will be immediately reverted to its last known state by the simulation.  Instead you can change the "out" variable.  The "out" variables are:

Power Plants:
CEG_out_P_Elek
CEG_out_P_Cher

Substations:
CEG_out_D_Elek
CEG_out_D_SZag
CEG_out_D_Cher
CEG_out_D_Zele
CEG_out_D_Bere
CEG_out_D_Soln

By making an "out" variable false, players will be able to manually close circuit breakers to make it true again (if not disabled by CEG_manual = false) or via the grid control system dialog.  

As an example, to "temporarily" turn off the lights in Solnichniy (and surrounding towns/areas) and allow players to be able to turn them back on, use the following code in your mission:

CEG_out_D_Soln = false;
publicVariable "CEG_out_D_Soln";

Be sure to only run this code on the server, and if at mission start, wait at least 5-10 seconds for the grids to be fully initialized first. Failure to use publicVariable could result in some clients not being updated and experience the pertinent effects (since street lamps states, sounds, and particles are all local).

2. Permanent Outages

If a mission maker wants to cause a permanent power outage/blackout that cannot be changed by players, the setVariable command can be used to accomplish this.  There is a logic co-located with each transformer object in game that controls the simulation at that object.  The logics are:

Power Plants:
CEG_logic_P_Elek
CEG_logic_P_Cher

Substations:
CEG_logic_D_Elek
CEG_logic_D_SZag
CEG_logic_D_Cher
CEG_logic_D_Zele
CEG_logic_D_Bere
CEG_logic_D_Soln

As an example, to "permanently" turn off the lights in Solnichniy (and surrounding towns/areas), use the following code in your mission:

CEG_logic_D_Soln setVariable ["operational", false, true];

Be sure to only run this code on the server, and if at mission start, wait at least 5-10 seconds for the grids to be fully initialized first.  To turn the power back on again, use the same code but change the "false" to "true" (always leave the second "true" in the array as "true" as that makes the value broadcast publicly):

CEG_logic_D_Soln setVariable ["operational", true, true];


V. SPECIAL CONSIDERATIONS
==========================

A. Entire Island Blackouts

If a mission maker wants to blackout the entire island, to do so you can use the "out" or setVariable methods demonstrated above with their pertinent temporary or permanent effects on both of the power plants (Elektrozavodsk and Chernogorsk).  Please be advised that doing so will most likely cause some lag due to the large number of public variables being broadcast and other code that runs on the clients to update the related effects.

1. Temporary Example:
--------------------

CEG_out_P_Elek = false;
publicVariable "CEG_out_P_Elek";

CEG_out_P_Cher = false;
publicVariable "CEG_out_P_Cher";


2. Permanent Example:
--------------------

CEG_logic_P_Elek setVariable ["operational", false, true];
CEG_logic_P_Cher setVariable ["operational", false, true];


B. Repairing/Re-Building Transformers and Power Plants

Although these occasions would be rare, for example during persistent warfare or RPG missions, it is possible to repair/re-build a destroyed transformer/power plant.  When a transformer or power plant is destroyed (rubble/ruins appear) the object's logic is immediately set "operational" false.  To restore power, use setDammage to change damage to any value less than 1 AND use the setVariable method demonstrated above to make the object "operational".  Example for Solnichniy:

(position CEG_logic_D_Soln nearestObject "Land_trafostanica_velka") setDammage 0;
CEG_logic_D_Soln setVariable ["operational", true, true];


C. Smokestacks

As of the current version of CEG, based on real life research and in-game considerations, if a smokestack at a power plant is destroyed, power is NOT cut off.  If a mission maker would like power to be cut off when a smokestack is destroyed, a method similar to the permanent blackout example above can be used.  The smokestack variables are:

Smokestacks:
CEG_on_S_Elek
CEG_on_S_Cher


Below is a trigger example and a script example of ensuring a power outage if a smokestack is detroyed:


1. Trigger Example:
---------------

Condition: !CEG_on_S_Elek

On Act: CEG_logic_P_Elek setVariable ["operational", false, true];


2. Script Example:
---------------

// destroySmokestack.sqf //


// Pause the script until the smokestack at the Elektrozavodsk power plant is destroyed.

waitUntil {!(CEG_on_S_Elek)};


// Make the Elektrozavodsk power plant inoperational and broadcast the change to all clients.

CEG_logic_P_Elek setVariable ["operational", false, true];


// End Script //


Additional Help
===============
For additional guidance on using CEG in your mission, please contact the developer (loyalguard) in the OFPEC forum or Bohemia Interactive forums (in the pertinent thread or via PM).